<div class="tmd-doc">
<h1 class="tmd-header-1">
Go Tips 101
</h1>
<p></p>
<div class="tmd-usual">
Index
</div>
<p></p>
<ul id="tips.html" class="tmd-list summaries">
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#force-to-use-keyed-struct-literals">How to force package users to use struct composite literals with field names?</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#make-struct-type-incomparable">How to make a struct type incomparable?</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#dont-use-assignments-with-expression-dependencies">Don't use value assignments with expressions interacting with each other.</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#simulate-loop-from-0-to-n">How to simulate <code class="tmd-code-span">for i in 0..N</code> in some other languages?</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#reset-pointers-for-dead-elements">We should reset the pointers in the element slots which are freed up in all kinds of slice manipulations to avoid memory leaking if we can't make sure if the freed-up element slots will be reused later.</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#avoid-copying-values-of-some-types">Values of some types in standard packages are not expected to be copied.</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#memclr">We can use the memclr optimization to reset some contiguous elements in an array or slice.</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#check-method-existence">How to check if a value has a method without importing the <code class="tmd-code-span">reflect</code> package?</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#clone-slice-efficiently-and-perfectly">How to efficiently and perfectly clone a slice?</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#use-three-index-subslice-form">We should use the three-index subslice form at some scenarios.</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#execute-deferred-calls-earlier">Use anonymous functions to make some deferred function calls be executed earlier.</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#assert-implementation">Make sure and show a custom defined type implements a specified interface type.</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#assert-at-compile-time">Some compile-time assertion tricks.</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#declare-max-int-uint">How to declare maximum int and uint constants?</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#detect-word-size-at-compile-time">How to detect native word size at compile time?</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#_64bit-alignment-guarantee">How to guarantee that the 64-bit value operated by a 64-bit atomic function call is always 64-bit aligned on 32-bit architectures?</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#avoid-boxing-large-size-values">Avoid boxing large-size values into interface values.</a>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<a href="#make-use-of-bce">Make optimizations by using BCE (bounds check elimination).</a>
</div>
</li>
</ul>
<p></p>
<div class="tmd-base summaries-items">
<p></p>
<h3 id="force-to-use-keyed-struct-literals" class="tmd-header-3">
How to force package users to use struct composite literals with field names?
</h3>
<p></p>
<div class="tmd-usual">
Package developers can put a non-exported zero-size field in a struct type definition, so that compilers will forbid package users using composite literals with some field items but without field names to create values of the struct type.
</div>
<p></p>
<div class="tmd-usual">
An example:
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">// foo.go
package foo

type Config struct {
	_    [0]int
	Name string
	Size int
}
</code></pre>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">// main.go
package main

import "foo"

func main() {
	//_ = foo.Config{[0]int{}, "bar", 123} // error
	_ = foo.Config{Name: "bar", Size: 123} // compile ok
}
</code></pre>
<p></p>
<div class="tmd-usual">
Please try not to place the zero-size non-exported field as the last field in the struct, for <a href="unofficial-faq.html#final-zero-size-field">doing so might enlarge the size of the struct type</a>.
</div>
<p></p>
<p></p>
<h3 id="make-struct-type-incomparable" class="tmd-header-3">
How to make a struct type incomparable?
</h3>
<p></p>
<div class="tmd-usual">
Sometimes, we want to avoid a custom struct type being used a map key types, then we can put a field of a non-exported zero-size incomparable type in a struct type to make the struct type incomparable. For example:
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">package main

type T struct {
	dummy        [0]func()
	AnotherField int
}

var x map[T]int // compile error: invalid map key type T

func main() {
	var a, b T
	_ = a == b // compile error: invalid operation:
}
</code></pre>
<p></p>
<h3 id="dont-use-assignments-with-expression-dependencies" class="tmd-header-3">
Don't use value assignments with expressions interacting with each other.
</h3>
<p></p>
<div class="tmd-usual">
Currently (Go 1.25), there are <a href="https://github.com/go101/go101/wiki/Some-evaluation-orders-in-multi-value-assignments-are-unspecified">some evaluation orders in a multi-value assignment are unspecified</a> when the expressions involved in the multi-value assignment interact with each other. So try to split a multi-value assignment into multiple single value assignments if there are, or you can't make sure whether or not there are, dependencies between the involved expressions.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
In fact, in some bad-written single-value assignments, there are also expression evaluation order ambiguities. For example, the following program might print <code class="tmd-code-span">[7 0 9]</code>, <code class="tmd-code-span">[0 8 9]</code>, or <code class="tmd-code-span">[7 8 9]</code>, depending on compiler implementations.
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">package main

import "fmt"

var a = &amp;[]int{1, 2, 3}
var i int
func f() int {
	i = 1
	a = &amp;[]int{7, 8, 9}
	return 0
}

func main() {
	// The evaluation order of "a", "i"
	// and "f()" is unspecified.
	(*a)[i] = f()
	fmt.Println(*a)
}
</code></pre>
<p></p>
<div class="tmd-usual">
In other words, a function call in a value assignment may the evaluation results of the non-function-call expressions in the same assignment. Please read <a href="evaluation-orders.html">evaluation orders in Go</a> for details.
</div>
<p></p>
<p></p>
<h3 id="simulate-loop-from-0-to-n" class="tmd-header-3">
How to simulate <code class="tmd-code-span">for i in 0..N</code> in some other languages?
</h3>
<p></p>
<div class="tmd-usual">
We can range over an array with zero-size element or a nil array pointer to simulate such a loop. For example:
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">package main

import "fmt"

func main() {
	const N = 5

	for i := range [N]struct{}{} {
		fmt.Println(i)
	}
	for i := range [N][0]int{} {
		fmt.Println(i)
	}
	for i := range (*[N]int)(nil) {
		fmt.Println(i)
	}
}
</code></pre>
<p></p>
<div class="tmd-usual">
Note, since Go 1.22, we can just use <code class="tmd-code-span">for i = range N</code>.
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">package main

import "fmt"

func main() {
	const N = 5

	for i := range N {
		fmt.Println(i)
	}
}
</code></pre>
<p></p>
<h3 id="reset-pointers-for-dead-elements" class="tmd-header-3">
We should reset the pointers in the element slots which are freed up in all kinds of slice manipulations to avoid memory leaking if we can't make sure if the freed-up element slots will be reused later.
</h3>
<p></p>
<div class="tmd-usual">
Please read how to <a href="container.html#delete-slice-elements">delete slice elements</a> and <a href="memory-leaking.html#dead-slice-elements">kind-of memory leaking caused by not resetting pointers in dead slice elements</a> for details.
</div>
<p></p>
<p></p>
<h3 id="avoid-copying-values-of-some-types" class="tmd-header-3">
Values of some types in standard packages are not expected to be copied.
</h3>
<p></p>
<div class="tmd-usual">
Values of the <code class="tmd-code-span">bytes.Buffer</code> type, <code class="tmd-code-span">strings.Builder</code> type and the types in the <code class="tmd-code-span">sync</code> standard package are not recommended to be copied. (They really should not be copied, though it is no problems to copy them under some specified circumstances.)
</div>
<p></p>
<div class="tmd-usual">
The implementation of <code class="tmd-code-span">strings.Builder</code> will detect invalid <code class="tmd-code-span">strings.Builder</code> value copies. Once such a copy is found, panic will occur. For example:
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">package main

import "strings"

func main() {
	var b strings.Builder
	b.WriteString("hello ")
	var b2 = b
	b2.WriteString("world!") // panic here
}
</code></pre>
<p></p>
<div class="tmd-usual">
Copying values of the types in the <code class="tmd-code-span">sync</code> standard package will be warned by the <code class="tmd-code-span">go vet</code> command provided in Go Toolchain.
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">// demo.go
package demo

import "sync"

func f(m sync.Mutex) { // warning
	m.Lock()
	defer m.Unlock()
	// do something ...
}
</code></pre>
<p></p>
<pre class="tmd-code output">
$ go vet demo.go
./demo.go:5: f passes lock by value: sync.Mutex
</pre>
<p></p>
<div class="tmd-usual">
Copying <code class="tmd-code-span">bytes.Buffer</code> values will never be detected at run time nor by the <code class="tmd-code-span">go vet</code> command. Just be careful not to do this.
</div>
<p></p>
<h3 id="memclr" class="tmd-header-3">
We can use the memclr optimization to reset some contiguous elements in an array or slice.
</h3>
<p></p>
<div class="tmd-usual">
Please read <a href="container.html#memclr">the <code class="tmd-code-span">memclr</code> optimization</a> for details.
</div>
<p></p>
<p></p>
<h3 id="check-method-existence" class="tmd-header-3">
How to check if a value has a method without importing the <code class="tmd-code-span">reflect</code> package?
</h3>
<p></p>
<div class="tmd-usual">
Use the way in the following example. (Assume the method needed to be checked is <code class="tmd-code-span">M(int) string</code>.)
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">package main

import "fmt"

type A int
type B int
func (b B) M(x int) string {
	return fmt.Sprint(b, ": ", x)
}

func check(v interface{}) bool {
	_, has := v.(interface{M(int) string})
	return has
}

func main() {
	var a A = 123
	var b B = 789
	fmt.Println(check(a)) // false
	fmt.Println(check(b)) // true
}
</code></pre>
<p></p>
<h3 id="clone-slice-efficiently-and-perfectly" class="tmd-header-3">
How to efficiently and perfectly clone a slice?
</h3>
<p></p>
<div class="tmd-usual">
Please read <a href="https://github.com/go101/go101/wiki/How-to-perfectly-clone-a-slice%3F">this wiki article</a> and <a href="https://github.com/go101/go101/wiki/How-to-efficiently-clone-a-slice%3F">this wiki article</a> for details.
</div>
<p></p>
<h3 id="use-three-index-subslice-form" class="tmd-header-3">
We should use the three-index subslice form at some scenarios.
</h3>
<p></p>
<div class="tmd-usual">
Assume a package provides a <code class="tmd-code-span">func NewX(...Option) *X</code> function, and the implementation of this function will merge the input options with some internal default options, then the following implementation is not recommended.
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">func NewX(opts ...Option) *X {
	options := append(opts, defaultOpts...)
	// Use the merged options to build and return a X.
	// ...
}
</code></pre>
<p></p>
<div class="tmd-usual">
The reason why the above implementation is not recommended is the <code class="tmd-code-span">append</code> call may modify the underlying <code class="tmd-code-span">Option</code> sequence of the argument <code class="tmd-code-span">opts</code>. For most scenarios, it is not a problem. But for some special scenarios, it may cause some unexpected results.
</div>
<p></p>
<div class="tmd-usual">
To avoid modifying the underlying <code class="tmd-code-span">Option</code> sequence of the input argument, we should use the following way instead.
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">func NewX(opts ...Option) *X {
	opts = append(opts[:len(opts):len(opts)], defaultOpts...)
	// Use the merged options to build and return a X.
	// ...
}
</code></pre>
<p></p>
<div class="tmd-usual">
On the other hand, for the callers of the <code class="tmd-code-span">NewX</code> function, it is not a good idea to think and rely on the <code class="tmd-code-span">NewX</code> function will not modify the underlying elements of the passed slice arguments, so it is best to pass these arguments with the three-index subslice form.
</div>
<p></p>
<div class="tmd-usual">
Another scenario at which we should use three-index subslice form is mentioned in <a href="https://github.com/go101/go101/wiki/The-capacity-of-the-result-byte-%28or-rune%29-slice-of-a-conversion-from-a-string-is-undefined">this wiki article</a>.
</div>
<p></p>
<div class="tmd-usual">
One drawback of three-index subslice forms is they are some verbose. In fact, I ever made <a href="https://github.com/golang/go/issues/25638">a proposal</a> to make it less verbose, but it was declined.
</div>
<p></p>
<p></p>
<h3 id="execute-deferred-calls-earlier" class="tmd-header-3">
Use anonymous functions to make some deferred function calls be executed earlier.
</h3>
<p></p>
<div class="tmd-usual">
Please read <a href="defer-more.html#kind-of-resource-leaking">this article</a> for details.
</div>
<p></p>
<p></p>
<h3 id="assert-implementation" class="tmd-header-3">
Make sure and show a custom defined type implements a specified interface type.
</h3>
<p></p>
<div class="tmd-usual">
We can assign a value of the custom defined type to a variable of type of the specified interface type to make sure the custom type implements the specified interface type, and more importantly, to show the custom type is intended to implement which interface types. Sometimes, writing docs in runnable code is much better than in comments.
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">package myreader

import "io"

type MyReader uint16

func NewMyReader() *MyReader {
	var mr MyReader
	return &amp;mr
}

func (mr *MyReader) Read(data []byte) (int, error) {
	switch len(data) {
	default:
		*mr = MyReader(data[0]) &lt;&lt; 8 | MyReader(data[1])
		return 2, nil
	case 2:
		*mr = MyReader(data[0]) &lt;&lt; 8 | MyReader(data[1])
	case 1:
		*mr = MyReader(data[0])
	case 0:
	}
	return len(data), io.EOF
}

// Any of the following three lines ensures
// type *MyReader implements io.Reader.
var _ io.Reader = NewMyReader()
var _ io.Reader = (*MyReader)(nil)
func _() {_ = io.Reader(nil).(*MyReader)}
</code></pre>
<p></p>
<h3 id="assert-at-compile-time" class="tmd-header-3">
Some compile-time assertion tricks.
</h3>
<p></p>
<div class="tmd-usual">
Besides the above one, there are more compile-time assertion tricks.
</div>
<p></p>
<div class="tmd-usual">
Several ways to guarantee a constant <code class="tmd-code-span">N</code> is not smaller than another constant <code class="tmd-code-span">M</code> at compile time:
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">// Any of the following lines can guarantee N &gt;= M
func _(x []int) {_ = x[N-M]}
func _(){_ = []int{N-M: 0}}
func _([N-M]int){}
var _ [N-M]int
const _ uint = N-M
type _ [N-M]int

// If M and N are guaranteed to be positive integers.
var _ uint = N/M - 1
</code></pre>
<p></p>
<div class="tmd-usual">
One more way which is stolen from <a href="https://twitter.com/lukechampine/status/1026695476811390976">@lukechampine</a>. It makes use of the rule that <a href="container.html#value-literals">duplicate constant keys can't appear in the same composite literal</a>.
</div>
<p></p>
<p></p>
<pre class="tmd-code disable-line-numbers111">
<code class="language-go">var _ = map[bool]struct{}{false: struct{}{}, N&gt;=M: struct{}{}}
</code></pre>
<p></p>
<div class="tmd-usual">
The above way looks some verbose but it is more general. It can be used to assert any conditions. It can be less verbose but needs a little more (negligible) memory:
</div>
<p></p>
<pre class="tmd-code disable-line-numbers111">
<code class="language-go">var _ = map[bool]int{false: 0, N&gt;=M: 1}
</code></pre>
<p></p>
<p></p>
<div class="tmd-usual">
Similarly, ways to assert two integer constants are equal to each other:
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">var _ [N-M]int; var _ [M-N]int
type _ [N-M]int; type _ [M-N]int
const _, _ uint = N-M, M-N
func _([N-M]int, [M-N]int) {}

var _ = map[bool]int{false: 0, M==N: 1}

var _ = [1]int{M-N: 0} // the only valid index is 0
var _ = [1]int{}[M-N]  // the only valid index is 0

var _ [N-M]int = [M-N]int{}
</code></pre>
<p></p>
<div class="tmd-usual">
Ways of how to assert a constant string is not blank:
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">type _ [len(aStringConstant)-1]int
var _ = map[bool]int{false: 0, aStringConstant != "": 1}
var _ = aStringConstant[:1]
var _ = aStringConstant[0]
const _ = 1/len(aStringConstant)
</code></pre>
<p></p>
<div class="tmd-usual">
The last line is stolen from Jan Mercl's <a href="https://groups.google.com/d/msg/golang-nuts/w1-JQMaH7c4/qzBFSPImBgAJ">clever idea</a>.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
Sometimes, to avoid package-level variables consuming too much memory, we can put assertion code in a function declared with the blank identifier. For example,
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">func _() {
	var _ = map[bool]int{false: 0, N&gt;=M: 1}
	var _ [N-M]int
}
</code></pre>
<p></p>
<h3 id="declare-max-int-uint" class="tmd-header-3">
How to declare maximum int and uint constants?
</h3>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">const MaxUint = ^uint(0)
const MaxInt = int(^uint(0) &gt;&gt; 1)
</code></pre>
<p></p>
<h3 id="detect-word-size-at-compile-time" class="tmd-header-3">
How to detect native word size at compile time?
</h3>
<p></p>
<div class="tmd-usual">
This tip is Go unrelated.
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">const Is64bitArch = ^uint(0) &gt;&gt; 63 == 1
const Is32bitArch = ^uint(0) &gt;&gt; 63 == 0
const WordBits = 32 &lt;&lt; (^uint(0) &gt;&gt; 63) // 64 or 32
</code></pre>
<p></p>
<h3 id="_64bit-alignment-guarantee" class="tmd-header-3">
How to guarantee that the 64-bit value operated by a 64-bit atomic function call is always 64-bit aligned on 32-bit architectures?
</h3>
<p></p>
<div class="tmd-usual">
Please read <a href="memory-layout.html">Go value memory layouts</a> for details.
</div>
<p></p>
<p></p>
<h3 id="avoid-boxing-large-size-values" class="tmd-header-3">
Avoid boxing large-size values into interface values.
</h3>
<p></p>
<div class="tmd-usual">
When a non-interface value is assigned to an interface value, a copy of the non-interface value will be boxed into the interface value. The copy cost depends on the size of the non-interface value. The larger the size, the higher the copy cost. So please try to avoid boxing large-size values into interface values.
</div>
<p></p>
<div class="tmd-usual">
In the following example, the costs of the latter two print calls are much lower than the former two.
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">package main

import "fmt"

func main() {
	var a [1000]int

	// This cost of the two lines is high.
	fmt.Println(a)                   // a is copied
	fmt.Printf("Type of a: %T\n", a) // a is copied

	// The cost of the two lines is low.
	fmt.Printf("%v\n", a[:])
	fmt.Println("Type of a:", fmt.Sprintf("%T", &amp;a)[1:])
}
</code></pre>
<p></p>
<div class="tmd-usual">
About value sizes of different types, please read <a href="value-copy-cost.html">value copy costs in Go</a>.
</div>
<p></p>
<p></p>
<h3 id="make-use-of-bce" class="tmd-header-3">
Optimize Go code by making use of BCE (bounds check elimination).
</h3>
<p></p>
<div class="tmd-usual">
Please read <a href="https://go101.org/optimizations/5-bce.html">this article</a> to get what is BCE and how well BCE is supported by the standard Go compiler now.
</div>
<p></p>
<p></p>
<p></p>
</div>
<p></p>
</div>
